<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>DB-&gt;set_re_source()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C API Reference" />
    <link rel="up" href="db.html" title="Chapter 2.  The DB Handle" />
    <link rel="prev" href="dbset_re_pad.html" title="DB-&gt;set_re_pad()" />
    <link rel="next" href="dbsort_multiple.html" title="DB-&gt;sort_multiple()" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">DB-&gt;set_re_source()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="dbset_re_pad.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
                The DB Handle
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="dbsort_multiple.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbset_re_source"></a>DB-&gt;set_re_source()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db.h&gt;

int
DB-&gt;set_re_source(DB *db, char *source);  </pre>
      <p>
         Set the underlying source file for the Recno access method.  The
         purpose of the <span class="bold"><strong>source</strong></span> value is to
         provide fast access and modification to databases that are normally
         stored as flat text files.
    </p>
      <p>
         The <span class="bold"><strong>source</strong></span> parameter specifies an
         underlying flat text database file that is read to initialize a
         transient record number index.  In the case of variable length
         records, the records are separated, as specified by 
         <a class="xref" href="dbset_re_delim.html" title="DB-&gt;set_re_delim()">DB-&gt;set_re_delim()</a>.  For
         example, standard UNIX byte stream files can be interpreted as a
         sequence of variable length records separated by &lt;newline&gt;
         characters.
    </p>
      <p>
         In addition, when cached data would normally be written back to the
         underlying database file (for example, the 
         <a class="xref" href="dbclose.html" title="DB-&gt;close()">DB-&gt;close()</a>  or 
         <a class="xref" href="dbsync.html" title="DB-&gt;sync()">DB-&gt;sync()</a>  methods are called),
         the in-memory copy of the database will be written back to the
         <span class="bold"><strong>source</strong></span> file.
    </p>
      <p>
         By default, the backing source file is read lazily; that is, records
         are not read from the file until they are requested by the
         application. <span class="bold"><strong>If multiple processes (not threads)
         are accessing a Recno database concurrently, and are either inserting
         or deleting records, the backing source file must be read in its
         entirety before more than a single process accesses the database, and
         only that process should specify the backing source file as part of
         the <a class="xref" href="dbopen.html" title="DB-&gt;open()">DB-&gt;open()</a>  call.  See the 
         <a class="link" href="dbset_flags.html#dbset_flags_DB_SNAPSHOT">DB_SNAPSHOT</a>  flag
         for more information.</strong></span>
    </p>
      <p>
         <span class="bold"><strong>Reading and writing the backing source file
         specified by <span class="bold"><strong>source</strong></span> cannot be
         transaction-protected because it involves filesystem operations that
         are not part of the Db transaction methodology.</strong></span> For this
         reason, if a temporary database is used to hold the records, it is
         possible to lose the contents of the <span class="bold"><strong>source</strong></span> file, for example, if the system crashes
         at the right instant.  If a file is used to hold the database, normal
         database recovery on that file can be used to prevent information
         loss, although it is still possible that the contents of <span class="bold"><strong>source</strong></span> will be lost if the system crashes.
    </p>
      <p>
         The <span class="bold"><strong>source</strong></span> file must already exist
         (but may be zero-length) when <a class="xref" href="dbopen.html" title="DB-&gt;open()">DB-&gt;open()</a>  is called.
    </p>
      <p>
         It is not an error to specify a read-only <span class="bold"><strong>source</strong></span> file when creating a database, nor is it
         an error to modify the resulting database. However, any attempt to
         write the changes to the backing source file using either the 
         <a class="xref" href="dbsync.html" title="DB-&gt;sync()">DB-&gt;sync()</a>  or 
         <a class="xref" href="dbclose.html" title="DB-&gt;close()">DB-&gt;close()</a>  methods will fail,
         of course. Specify the 
         <a class="link" href="dbclose.html#dbclose_DB_NOSYNC">DB_NOSYNC</a>  flag to the
         <a class="xref" href="dbclose.html" title="DB-&gt;close()">DB-&gt;close()</a>  method to
         stop it from attempting to write the changes to the backing file;
         instead, they will be silently discarded.
    </p>
      <p>
         For all of the previous reasons, the <span class="bold"><strong>source</strong></span> field is generally used to specify
         databases that are read-only for Berkeley DB applications; and that
         are either generated on the fly by software tools or modified using a
         different mechanism — for example, a text editor.
    </p>
      <p>
         The <code class="methodname">DB-&gt;set_re_source()</code> method configures operations performed using
         the specified <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a>  handle,
         not all operations performed on the underlying database.
    </p>
      <p>
         The <code class="methodname">DB-&gt;set_re_source()</code> method may not be called after the 
         <a class="xref" href="dbopen.html" title="DB-&gt;open()">DB-&gt;open()</a>  method is called. If
         the database already exists when 
         <a class="xref" href="dbopen.html" title="DB-&gt;open()">DB-&gt;open()</a>  is called, the
         information specified to <code class="methodname">DB-&gt;set_re_source()</code> must be the same as that
         historically used to create the database or corruption can occur.
    </p>
      <p>
         The <code class="methodname">DB-&gt;set_re_source()</code> <span>
            <span>
                  method returns a non-zero error value on failure and 0 on success.
            </span>
            
        </span>
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp50581832"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp50582024"></a>source</h4>
              </div>
            </div>
          </div>
          <p>
                          The backing flat text database file for a Recno database.
                     </p>
          <p>
                             When using a Unicode build on Windows (the default), the 
                             <span class="bold"><strong>source</strong></span>
                             argument will be interpreted as a UTF-8 string, which is equivalent to
                             ASCII for Latin characters.
                     </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp50584424"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
                         The <code class="methodname">DB-&gt;set_re_source()</code> <span>
            <span>
                 method may fail and return one of the following non-zero errors:
            </span>
            
        </span>
                    </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp50598120"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                If the method was called after <a class="xref" href="dbopen.html" title="DB-&gt;open()">DB-&gt;open()</a> 
                was called; or if an invalid flag value or parameter was specified.
            </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp50589024"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
                <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a>  
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp50600560"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                     <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 
                </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="dbset_re_pad.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="db.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="dbsort_multiple.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">DB-&gt;set_re_pad() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> DB-&gt;sort_multiple()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
